Developer CD Series 1992 …SCII & the Runetime Code/ADC Developer CD (1992-07) (''Butch ASCII And The Runtime Code'')_iso/Dev.CD 199207.iso/Development Platforms/Apple II/HyperCardIIGS/Developer Documentation/ASCII Text/HyperCard.ERS

Text File | 1992-02-24 | 39.0 KB | 1,061 lines | [TEXT/pdos]

HYPERCARD IIGS 1.1 ERS
c 1991-92 Apple Computer, Inc.  All Rights Reserved



Summary of HyperCard IIGS Version 1.1
Version 1.1 is an enhanced version of HyperCard IIGS version 1.0.  As
such, it includes all the features of HyperCard IIGS version 1.0
(referred to hereafter as version 1.0) as well as new features specific
to version 1.1.  Stacks created with version 1.0 are 100% compatible
with version 1.1.  Stacks created with the later version will continue
to function with version 1.0 provided the stacks do not take advantage
of features specific to version 1.1.  Stacks that use the new HyperTalk
features of 1.1 will generate HyperTalk errors if run under version 1.0.

HyperCard IIgs 1.1 is designed to function with the same memory
requirements as version 1.0.  It requires an Apple IIGS with at least
1.5 megabytes of memory and a hard disk.

Version 1.1 is System Software 6.0 aware and takes advantage of several
new system software features.  Version 1.1 will continue to run with
System Software 5.0.4 as did HyperCard IIgs version 1.0.

The new features of version 1.1 are designed to provide easier access to
commonly used scripting techniques, implement the most useful/practical
of the Macintosh HyperCard 2.1 features, provide a further
implementation of color, and take advantage of new features in System
Software.

Bugs fixed in version 1.1 consist of all known crashing bugs as well as
any bugs fixable within the scope of the 1.1 release.


Version 1.1 Features
This section describes all the new features of HyperCard IIgs 1.1 as
well as comparing them to similar or identical features of Macintosh
HyperCard 2.0/2.1.  The list below is comprised of visual changes as
well as discernible feature changes.  It does not include changes such
as speed enhancements or bug fixes which are included in a separate
section.

New property - "ItemDelimiter"
This new property allows the scripter to define any single character as
the delimiter character used to separate items in HyperTalk containers.
For example, the scripter wishes to locate the filename from within a
container that contains a complete pathname.  Using version 1.1 and the
itemDelimiter property, the scripter can do this:

Variable "bucket" contains:
    :Barney:HyperCard:Stacks:MyOwnStack

The user executes the following script:
    set the itemDelimiter to colon
    put last item of bucket

Version 1.1 responds with:
    MyOwnStack

The itemDelimiter property resets to the comma character at idle time so
as not to affect compatibility with stacks that assume the itemDelimiter
character is always a comma.  This property is identical to HyperCard
2.1.


New constants - "Comma" and "Colon"
Version 1.1 contains two new HyperTalk constants.  They are "colon" and
"comma."  These constants are designed to compliment the new
itemDelimiter property.

The user can now script:
    Set the itemDelimiter to colon
    or
    Set the itemDelimiter to comma

Instead of:
    Set the itemDelimiter to ":"
    or
    Set the itemDelimiter to ","

Note that the scripter is not restricted to using these constants and
can use any HyperTalk character or expression to define the
itemDelimiter character.

Feature enhancement - "Compact Stack"
Compacting a stack with free space in the resource fork caused by adding
and deleting resources will now compact the resource fork as well as the
data fork when the user chooses the Compact Stack menu item if:  (a)
the user holds down the option key, (b) the free space is > 50K, or (c)
the free space is > 10% of the resource fork size.

Command enhancement - "Ask"
The "Ask" command has been enhanced to return "Cancel" if the user
clicks the cancel button in addition to returning empty in the variable
"it."

The user can now script:
    ask "Please enter your name:"
    if the result is not "Cancel" then
      put it into userName
    end if

Property change - "Rect, top, topLeft, location"
The rect property of windows has been altered to be compatible with
Macintosh HyperCard.  HyperCard IIGS 1.0 would return a rect with the
top left corner starting at the top left of the window frame.  HyperCard
IIgs 1.1 and all versions of Macintosh HyperCard return the top left
corner of the content region.  The same applies when setting the top,
location, or topLeft of a window.  The coordinates specified define the
top left of the content region.  Scripts from HyperCard IIGS 1.0 that
specifically set a window to a certain location will cause the window to
appear six pixels higher than it did running under HyperCard IIgs 1.0.
This can be easily changed in the particular script.


New property - "BackColor"
A new property named "BackColor" has been added to fields and buttons.
This property determines the background color of a button or field.
HyperCard IIGS 1.0 is restricted to white backgrounds.

The user can access this new property with the following:
    set the backColor of button 1 to 15
    or
    set the backcolor of last field to 5

The backColor property is limited to an integer between 1 and 16
representing one of the sixteen colors available to user on that
particular card/background.  This property can also be accessed and
changed from the revised object color dialog boxes.

Changed dialog boxes - "Field Colors" and "Button Colors"
The dialog boxes which allow the user to view and modify the color
attributes of buttons and fields have been altered significantly.
Included on the next page are screenshots of the new dialog boxes.



Open File "HCGS.1" to see Figure 1 - HyperCard IIGS Field Colors Dialog




Open File "HCGS.2" to see Figure 2 - HyperCard IIGS Button Colors Dialog


Feature Enhancement - "Transparency"
The new backColor property interacts with transparent buttons and fields
to provide "tinted" buttons/fields similar to a stained glass effect.
Setting the backColor of a transparent button or field causes the
background of the part to be translucent, allowing objects behind the
part to show through to the foreground.  The choice of backColor
determines how the objects underneath show through and how they are
tinted.  Transparent objects created with version 1.0 always have a
backColor of white which is not affected by this feature.  Transparent
objects with a white background color will function identically to
version 1.0.

New Functions - "ClickLine" and "ClickChunk"
Version 1.1 contains two new functions that allow the scripter to easily
determine where in a particular field a user clicked.

Syntax for the clickLine, clickChunk functions:
    put the clickLine
    put the clickChunk
Or
    put clickLine()
    put clickChunk()

ClickLine returns the line clicked in this format:
    line 3 of card field 1

ClickChunk returns a chunk expression defining the text clicked on in
this form:
    char 5 to 9 of bkgnd field 6

ClickLine returns the line clicked relative to the actual text of the
field, not the way the text is word wrapped.  Therefore, a user can
click on the text on the second line of a field and have line one
returned since the first line of the field was long enough to wrap to
the second display line.  These functions are identical in
implementation to these functions in Macintosh HyperCard 2.0/2.1.

System Software 6.0 support
HyperCard IIgs 1.1 contains several features specific to the 6.0
environment.  If running under System Software 5.0.4, these features
will not be available.

    Detect disk insertions
    Version 1.1 will now detect disk insertions and respond
    appropriately at idle time.  If the disk is unreadable, a
    dialog box will be displayed asking the user if they wish
    to format the disk.

    Launching under System Software 6.0
    HyperCard IIgs 1.1 will not drop out of the SHR screen while
    launching, executing another GS/OS application, or quitting
    to the Finder.

    Finder support
    Version 1.1 contains Finder "info" resources containing icon,
    version, and copyright information as well as document types
    and paths.

    Command enhancement - "Play"
    The Play" command has been enhanced to work in conjunction
    with the new 6.0 Sound Control Panel.  If 6.0 is in use and the
    user attempts to play a sound that is not present in the
    current resource heirarchy, version 1.1 will query the
    Sound Control Panel to determine if a sound with that name
    exists in the Sounds folder of the boot disk.  If it does,
    version 1.1 will play the sound just as if it was present in a
    resource.  This process will be transparent to the end user.

XWindows
HyperCard IIgs 1.1 implements a subset of the XWindow concept from
Macintosh HyperCard 2.0/2.1.  Certain concepts such as those dealing
with an externally based script editor as in 2.0/2.1 are not
implemented.  The list below details the XWindow implementation of
HyperCard IIgs version 1.1.


HyperTalk Extensions
HyperCard IIgs 1.1 HyperTalk has been extended to include support for
moving, hiding, showing, and otherwise manipulating XWindows as easily
as the built-in windows such as the Tool, Pattern, and Go palettes.  In
addition, HyperTalk support for the built-in windows is improved and
expanded.  All the original methods of dealing with windows remain
intact and unchanged.

New Method of Referencing Windows - by Name, Number, or Ordinal.
Version 1.1 now supports referencing windows, both built-in and
external, in several new ways.  These new ways of referencing the
windows are compatible with 2.0/2.1.  Referencing a window in HyperCard
IIGS 1.0/HyperCard 1.2.5 was restricted to this:
    show tool window

Although this still functions, it is now possible to reference a window
in any one of the following methods:
    show tool window
    hide window tool
    show window "tool"
    close window "Fred"  <---- Assuming there is a window named "Fred"
    set the location of first window to 50,50
    get the visible of sixth window
    show last window
    show window 3
    show window id 69341 at 50,30
    hide any window

All of the existing commands and functions dealing with windows as well
as all new commands and functions now support this method of referencing
windows.  Note that only the built-in windows (Tool, Pattern, Card, and
Go) can be referenced in the old form of "<name> window."




Open File "HCGS.3" to see Figure 3 - HyperCard IIGS Windows


New Function - "windows"
Version 1.1 implements a new function which returns a return-delimited
list of all windows currently available. This is 2.0/2.1 compatible.  A
typical result of this function is below:
    Message
    Home      <------ The name of the card window is the current stack.
    Pattern
    Tool
    Go

Extension to Existing Function - "number of windows"
In addition to being able to determine the number of cards, bkgnds,
parts, etc.  version 1.1 can now report the number of available windows.
This is 2.0/2.1 compatible.  This number is the number of HyperCard
windows, it does not include DA windows or any others.

The user can script:
    put the number of windows

HyperCard IIgs 1.1 responds with:
    5

Extension to Existing Command "set"
Version 1.1 implements all of the properties previously supported for
built-in windows for external windows as well.  This includes location,
topLeft, location, visible, etc.  This is identical to 2.0/2.1.


Extension to Existing Command "Dial with Modem"
Executing the dial with modem command now attempts to dial the phone
with a serial or modem card if the built-in modem port is disabled.  The
logic for the dial command is this:
1) Look for the modem port, if slot 2 is set to "modem", send the modem
     dialing string out the built-in port.
2) If the built-in modem port is disabled, look for a character device
     in slot 2.  If found, send the modem dialing string to that card.
3) If the built-in port is disabled and slot 2 does not contain a
     character device, scan for a character device beginning at slot 1 and
     send the dialing command to the first one found.

Extension to Existing Command "Play"
Version 1.1 will now play any sound in the Sounds folder when using
System 6.0.  If a play command is given using a sound that is not in the
current resource heirarchy, HyperCard IIGS v.1.1 will call the Sound
CDEV  of  System 6.0 to determine whether a sound of that name exists
in the  folder.  If so, it is loaded and used just as any sound resource
would be.

New Window Property - "Name"
Version 1.1 now supports the read-only window property "name."  This
allows the user to determine a window name.  Commonly used when the user
only knows the window number.

The user can script:
    put the name of <windowReference>

HyperCard IIgs version 1.1 responds with something like:
    Pattern

New Window Property - "Number"
Version 1.1 now supports the read-only window property "number."  This
allows the user to determine a window number.  Commonly used when the
user only knows the window name.

The user can script:
    put the number of <windowReference>

HyperCard IIgs version 1.1 responds with something like:
    5

New Window Property - "ID"
Version 1.1 now supports the read-only window property "ID."  This
allows the user to determine the ID of a given window.  There are
several things to note regarding window IDs.  IDs for the built-in
windows are assigned when HyperCard IIgs starts up and will not change.
XWindow IDs are assigned when the window is created and released when
the window is closed.  Window IDs may vary for any window from machine
to machine.

The user can script:
    put the id of <windowReference>

HyperCard IIgs version 1.1 responds with something like:
    69341

Extension to Existing Command - "Close"
The Close command has been extended to included support for closing
external windows as well as closing text files and printing jobs.  Only
external windows may be closed.  Attempting to close a built-in window
will result in the error message "Can't close that window."  Syntax for
closing external windows is:
    close <windowReference>

The Close command supports all forms of window references and is
HyperCard 2.0/2.1 compatible.


Extensions to the XCMD Interface
Version 1.1 contains several new callbacks dealing with the
implementation of XWindows as well as related utility callbacks.  These
callbacks are accessed with a set of new HyperXCMD interfaces files
providing access to the callbacks from Pascal, C, and Assembly Language.
As many of the new callbacks as possible are modeled after their
Macintosh HyperCard 2.0/2.1 counterparts within the scope of our XWindow
implementation.  Following is a list and general description of the new
callbacks.

New Callback - "StrToRect"
PROCEDURE StrToRect(str: Str255; VAR rct: Rect);
    Inputs    str    String containing text to convert to a rect
    Outputs    rct    Rect containing specified coordinates
This callback converts a Pascal string containing alphanumeric
characters delimited by commas designating a rectangle to a true, four
integer rect record.  Pascal interface is above.

New Callback - "RectToStr"
PROCEDURE RectToStr(rct: Rect; VAR str: Str255);
    Inputs    rct    Rect containing coordinates to convert
    Outputs    str    String containing alphanumeric representation
             of rect
The complement of StrToRect, this callback converts a rect record back
to a string.

New Callback - "StrToPoint"
PROCEDURE StrToPoint(str: Str255; VAR pt: Point);
    Inputs    str    String containing text to convert to a point
    Outputs    pt    Point containing specified coordinates
This callback converts a Pascal string containing alphanumeric
characters delimited by commas designating a point to a true, two
integer point record.

New Callback - "PointToStr"
PROCEDURE PointToStr(pt: Point; VAR str: Str255);
    Inputs    pt    Point containing coordinates to convert
    Outputs    str    String containing alphanumeric representation
             of point
The complement of StrToPoint, this callback converts a point record back
to a string.

New Callback - "NewXWindow"
FUNCTION NewXWindow(boundsRect: Rect; windName: Str31
                    visible: BOOLEAN, windowStyle: INTEGER): WindowPtr;
    Inputs    boundsRect    Rect for newly created window
        windName    Name used for HyperTalk references to
                 the window and, optionally, displayed
                 depending on the window type.
        visible        Whether to create the new window
                initially visible
        windowStyle    Style of the XWindow.  0 = windoid, 1 =
                rectangle, 2 = shadow, 3 = dialog box.
    Outputs    windowPtr    Pointer to a standard window record
                defining the new window.
This callback allows an external command to create and register a
window.  In addition to creating the window, HyperCard also adds the new
window to its internal list of external windows and keeps the XCMD in
memory after it terminates so that it can respond to events concerning
the window.  The windows created are standard IIGS windows and can be
manipulated in the same way as a window created from within a stand-
alone application with two exceptions.
(1)  The XCMD must never call the toolbox routine CloseWindow on the
XWindow.  External commands MUST use the CloseXWindow callback to
dispose of a window.
(2)  External commands must not alter the wRefCon field of the window
record.  This field is reserved for HyperCard.  External commands
needing to save or restore data associated with a particular window can
use the SetXWindowValue and GetXWindowValue callbacks.

New Callback - "CloseXWindow"
PROCEDURE CloseXWindow(window: WindowPtr);
    Inputs    window    Pointer to a window record designating the
            window to be closed
    Outputs    <none>
This callback send an xCloseEvt to the owner external, closes the
window, and disposes of all memory HyperCard has allocated for the
window.  XCMDs that create windows are responsible for disposing of any
memory they have allocated when they receive an xCloseEvt.

New Callback - "SetXWindowValue"
PROCEDURE SetXWindowValue(window: WindowPtr; customValue: LongInt);
    Inputs    window        Pointer to window associated with the
                value
        customValue    Four byte value containing data to
                store with the window
    Outputs    <none>
This callback allows an external command to store a four byte value
along with any XWindow.  This value will typically be a pointer or
handle to a block of memory containing information the external command
wishes to keep intact regarding the contents of the XWindow.  Because
external commands can execute and terminate many times in response to
events, data cannot be kept in standard variables.

New Callback - "GetXWindowValue"
FUNCTION GetXWindowValue(window: WindowPtr): LongInt;
    Inputs    window        Pointer to window associated with the
                 value
    Outputs    customValue    Four byte value containing the
                data stored with the window

New Callback - "HideHCPalettes"
PROCEDURE HideHCPalettes;
    Inputs    <none>
    Outputs    <none>
This callback hides all currently visible windows, both built-in and
XWindows.  Additionally, it stores internally which windows were visible
at the time it was called so that a subsequent call to ShowHCPalettes
will display the same set of windows.  This callback is commonly used
when an external command needs to clear the screen such as when using
the video overlay card.

New Callback - "ShowHCPalettes"
PROCEDURE ShowHCPalettes;
    Inputs    <none>
    Outputs    <none>
This callback displays all windows hidden with the HideHCPalettes
callback.  If HideHCPalettes was not called, this callback does not
display any windows.

New Callback - "SetXWIdleTime"
PROCEDURE SetXWIdleTime(window: WindowPtr; interval: LongInt);
    Inputs    window        Pointer to owner window
        interval        Length (in ticks) between idle events
    Outputs    <none>
External commands that create XWindows will normally receive xIdleEvt
events periodically.  Because HyperCard IIgs must spend time generating
and sending these events, an external command can tell HyperCard IIgs
how often it wants these events.  Setting the interval to zero will
cause HyperCard IIgs to not send any idle events.  Setting the interval
to a very small number will cause HyperCard IIgs to send xIdleEvt events
as quickly as possible.  Because of the overhead involved in generating
and sending an event, an external command should not depend on receiving
xIdleEvt events at exact intervals.  In addition, xIdleEvt events are
only sent at HyperCard IIgs idle time and may be postponed for lengthy
intervals while scripts are running.

New Callback - "XWAllowReEntrancy"
PROCEDURE XWAllowReEntrancy(window: WindowPtr; allowSysEvts: BOOLEAN;
             allowHCEvts: BOOLEAN);
    Inputs    window    Pointer to owner window
        allowSysEvts    Whether to allow reentrant system
                 events
        allowHCEvts    Whether to allow reentrant HyperCard
                events
External commands have control over whether to allow reentrant events.
That is, whether to allow an event to be sent to an external that is
still executing in response to another event.  The default is not to
allow recursive calls to an external command.


Events Dealing with XWindows
External commands that create XWindows are kept in memory after they
terminate so that they may be called in response to events concerning
the XWindows they created.  An XCMD can determine whether it has been
called from a script or the message box or in response to an event by
checking the paramCount field of the parameter block.  If this value is
negative, the XCMD has been called in response to an event.  The
following Pascal code fragment illustrates this concept.

    BEGIN {SampleXCMD}
      { If the paramCount is negative, we have been called in response
        to an event }
      IF paramPtr^.paramCount < 0 THEN BEGIN
        HandleEvents;
        EXIT(SampleXCMD);
      END; {if}

      { program continues... }

The Events an External Command Can Receive
The following is a list of all events an external command can receive
along with a description of the event.  Some of the events are standard
system events while others are generated by HyperCard.

HyperCard Event - "xOpenEvt"
xOpenEvt is the first event sent to any XWindow.  This event is sent to
any new XWindows immediately after the parent XCMD terminates.  No
events will be sent to an XWindow before this event.

HyperCard Event - "xCloseEvt"
This is HyperCard's method of notifying the XCMD that a window that it
created is being closed.  At the time of the event, the window is still
present and visible.  The window will be closed immediately following
the event.  The owner XCMD should not call CloseXWindow or close the
window in any other means when it receives this event.  HyperCard will
handle closing the window when the XCMD returns control.  XCMDs will
typically use this event to dispose of any additional memory they have
allocated for the XWindow.

HyperCard Event - "xHidePalettesEvt"
This event is sent to all XWindows when an external command executes the
HideHCPalettes callback.  An external command may wish to deallocate
memory or take other action when the user hides their window in this
manner.

HyperCard Event - "xShowPalettesEvt"
This event is sent to all XWindows when an external command executes the
ShowHCPalettes callback.  An external command may need to prepare itself
to handle update events, etc, if it has deallocated the memory when
being hidden.

HyperCard Event - "xCursorWith"
This event is sent to an XWindow when the mousecursor enters therect of
their window.  The owner XCMD can then set the cursor to a custom shape
if desired using the GS Toolbox.  If they do not wish to handle the
changing of the cursor shape, the external command should set the
passFlag of the parameter block to TRUE so that HyperCard IIgs will
handle the cursor itself.  Since this message is sent repeatedly, as
long as the cursor is within the window, the XCMD should determine
whether it has already changed the cursor shape before doing so again to
avoid flickering of the cursor and slowing down the CPU.

System Event - "UpdateEvt"
This event indicates the all or part of the specified window needs to be
updated.  It is the responsibilty of the owner external of each window
to handle redrawing the contents of the window in response to this
event.

System Event - "MouseDownEvt"
The user has pressed the mouse button while the mouse pointer was within
an external window.  The external command will commonly handle tracking
the mouse click manually, or call FindControl and have the control
manager do so.

System Event - "NullEvt"
This event will only be sent if the XCMD/XFCN has enabled idle events by
setting the idle interval to a value other than zero with the
SetXWIdleTime callback.  See the description of this callback above for
more information regarding using null events.


Care and Feeding of Your New XWindow
An XCMD that creates an XWindow is treated differently from an XCMD that
doesn't.  The following section details differences the XCMD author
needs to be aware of.

1)  XCMDs that create external windows are kept in memory as long as any
XWindows that XCMD created are open.
2)  XWindow XCMDs should not assume that they own only one window.
Subsequent calls to the XCMD may create additional windows.  The XCMD
should use the windowPtr passed and the GetXWindowValue and
SetXWindowValue calls to determine the appropriate action to take in
response to a particular event.
3)  The same Memory Manager user ID is passed to an XWindow owner XCMD
as long as any of the XWindows the XCMD owns are open.  The XCMD should
not perform a DisposeAll on its memory ID because other windows that the
XCMD is responsible for could still be open.
4)  The wFrameBits field of an XWindow is inaccessible to an XCMD, XCMDs
should not attempt to modify the standard window attributes of a
windoid.
5)  XWindow owners that close all of their XWindows will be disposed of
when there are no more pending calls to them.


Major Bug Fixes in HyperCard IIgs 1.1
This section lists the bugs present in version 1.0 that are addressed in
HyperCard IIgs 1.1.  This is not a complete list of all bug fixes but
rather a guide to major differences in version 1.0 and version 1.1 that
a user could encounter.

Project Area    Bug Description            Scope of Bug Fix

Memory Mgmt.    Last sound played is left in     Version 1.1 now
        memory locked and unpurgeable     cleans up
        until another sound is played     sounds at idle
        at which point that sound is     time.
        left locked and unpurgeable.

Externals    If an XCMD is passed an argument     Added error check
         that necessitates leaving the     and recovery for this
        stack which contains the XCMD,    situation.
        version 1.0 would crash.

Interpreter    Internal hash values were not     Localized assembly
        being generated correctly,     fix.
        slowing HyperTalk
        execution speed.

Read Command    Read command could orphan a 4K    Rewrite of Read
        handle in out of memory conditions.    command.
        Command is also wasteful of
        memory and inefficient.

Clipboard    Version 1.0 was using an         Change to using
        undocumented scrap type         documented type.
        for palettes.

Cursors        Several cases where version     Modified problem
        1.0 wasn't restoring the cursor     routines to
        shape correctly.            save/restore
                        cursor correctly.

Edit Menu    Edit Menu IDs off-by-one for DAs.      Modified to use
        Copy would be Cut, Paste would be     correct values.
        Copy, etc.

HyperTalk    Saving a copy of a stack from     Now save the wet
        HyperTalk while in the Paint     paint on the correct
        tools with wet paint present    card before the
         would result in the paint being    copy.
        saved on the first card of the
        source stack being copied.

Paint Tools    Fonts loaded or generated when    Correctly set fonts
        using paint text were not         as purgeable after
        released.             use.

Visual Effects    Using visual effect dissolve     No longer crashes.
        with a completely obscured card
        window causes a crash.

HyperTalk    The Dial command would not     Version 1.1 now
        utilize a modem or serial card.    looks for a character
                        device, preferrably
                         in slot 2, if the
                        built-in modem port is
                        overridden.

Memory Mgmt.    Internal PLib routine that copies    Patched out PLIB
        blocks of memory contained a bug    routine with fixed
        that would overwrite a word of    version.
         memory if the area being copied
        was an odd number of bytes and
        crossed a bank.

HyperTalk    Using the "write at" syntax of the      This 1.0 bug is fixed
        write command to write at a point     within Version 1.1
        beyond the eof of a file would not     so that it zeros
        clear the data between the     the data.
        previous eof and the new mark
        when writing to an AppleShare or
        HFS volume.

Screen Update    Scrolling a field then moving     Fixed.
        windows over top of it would
        cause the field to refresh
        incorrectly.

Renaming a Stack    Changing the case of a character    Fixed.
         of the name of a stack would not
        rename the stack.

HyperTalk    Opening a ProDOS 8 application     Now correctly using
        "with"a document was incorrectly     slashes.
        using colons to specify the
        document path.

HyperTalk    Executing an invalid callback     Now call
        number would execute a brk     SysFailMgr.
        instruction, exiting to the
        debugger or monitor.

Speed Improvements
Listed below are specific areas that have been improved as far as
execution speed.  While many improvements within the program as far as
overall speed and responsiveness have been implemented, this section
details speed improvements local to a specific area.

Project Area    Description of Speed Improvement
Icon Picker    Time to display the icon picker when choosing an icon
        for a button has been drastically reduced.  Most
        apparent when displaying many icons as in the Button
         Ideas stack.

Interpreter    (Also listed in bug fixes.)  Internal hash values were
        being generated incorrectly, reducing execution speed.
         Hash values now generated correctly.

Interpreter    Internal interpreter routines rewritten in assembly.

Graphics        Internal picture unpacking algorithm rewritten in
        assembly for improved speed.

Button Hiliting    Version 1.0 writes the hilite of auto-hilite buttons to
         disk every time they are clicked regardless of whether
         the button actually changed state.  HyperCard IIGS
         version 1.1 only writes auto-hilite buttons to disk if
        the state actually changes, saving a disk  access for
        every mouse click.

Button/Fields    Button and field drawing code is now all assembly.


Code Size/Memory Usage
HyperCard IIgs version 1.1 is smaller in code size than HyperCard IIGS
version 1.0 even with the addition of the new features because version
1.1 is compiled with a later version of the Pascal IIGS compiler which
generates smaller/faster code and because of routines rewritten in
assembly which is inherently smaller than most compiled Pascal code as
well as more efficient.  Optimizing of Pascal code has also resulted in
smaller code size and memory usage.

Version 1.1 manages memory more efficiently and will work better than
version 1.0 in low memory situations because of the memory management
bugs fixed as noted above and because of reorganized global variable
usage and new code segmentation used throughout the program.



Sample XWindow Code (Pascal)
Included below is the source code for a sample XCMD.  This is a much
simplified version of the Picture XCMD that appears in the Scripter's
Tools stack.  The complete source to that XCMD is also available as
sample source code.

{---------------------------------------------------------------------

  file Picture.p

  Part of HyperCard IIGS 1.1

  Copyright c 1991 Apple Computer, Inc.

  This XCMD has the following syntax:
    Picture resName [, windowStyle]

    INPUTS:    resName    Name of pict resource to draw in the window
        windowStyle    (Optional)  Defines the appearance of the
                 picture window.  Can be rect, rectangle,
                shadow, or dialog.  Any other text or not
                specified results in a standard windoid.

  This XCMD creates and maintains an XWindow.  The XWindow contains
  a picture retrieved from a resource with a name specified by the
  caller.  If the resource cannot be found, the XWindow is still
  created and the text "Unable to draw picture." is displayed.

  Author:    Darin Acquistapace
  Created:    5/22/91
  Modified:    See Mod History Below


  Modification History:

    5/22/91 - New today.
    5/30/91- Updated for revised XWindow callbacks
    6/04/91 - Added HyperCard version check.
    6/12/91 - Changed from wInContent to mouseDownEvt for mouseDowns.
    6/14/91 - Added XWAllowReEntrancy for release with 1.1d10.
    6/24/91 - Modified to work with "real" custom defProc XWindows.
    6/31/91 - Added support for xCursorWithin message.
    8/19/91 - Added support for multiple window styles.

---------------------------------------------------------------------}

UNIT DummyUnit;

{$Z+ }
{$N+ }

INTERFACE

USES
  Types, Memory, MiscTool, GSOS, QuickDraw, Resources, QDAux, Events,
  Controls, Windows, Menus, HyperXCMD;

PROCEDURE EntryPoint(paramPtr: XCmdPtr);

IMPLEMENTATION

PROCEDURE XPicture(paramPtr: XCmdPtr);
    FORWARD;

PROCEDURE EntryPoint(paramPtr: XCmdPtr);
BEGIN
  XPicture(paramPtr);
END;

PROCEDURE XPicture(paramPtr: XCmdPtr);
CONST
    ScriptErrStr    = 'Can''t understand arguments of XCMD
Picture.';
    CopyrightStr    = 'Picture XCMD v1.0d7" & return &
                  "by Darin Acquistapace, 5/22/91" & return
                   & "c 1991 Apple Computer, Inc.';
    HelpStr        = 'FORM:  Picture ResourceName [, windowStyle]';
    WrongVersionStr     = 'Picture XCMD requires HyperCard IIGS 1.1';
    CreateErrStr    = 'Unable to create window';
    CantDrawStr        = 'Unable to draw picture.';
    RectStr1        = 'rect';
    RectStr2        = 'rectangle';
    ShadowStr        = 'shadow';
    DialogStr        = 'dialog';
VAR
    pCount:        INTEGER;
    windowStyle:    INTEGER;
    sampleXWindow:    WindowPtr;
    windRect:        Rect;
    str:            Str255;
    styleStr:        Str255;

    PROCEDURE HTError;
    { Puts the specified string into the result and terminates with a
        HyperTalk error}
    BEGIN
      ParamPtr^.ReturnValue := PasToZero(ScriptErrStr);
      ParamPtr^.ReturnStat := 1;
      EXIT(XPicture);
    END; {HTError}

    PROCEDURE ReturnResult(str: Str255);
    { Puts the specified string into the result and terminates }
    BEGIN
      ParamPtr^.ReturnValue := PasToZero(str);
      EXIT(XPicture);
    END; {ReturnResult}

    PROCEDURE CommandInfo(Msg : str255);
    { Puts the specified string into a dialog box and terminates }
    BEGIN
      SendHCmessage(concat('answer "', Msg, '"'));
      EXIT(XPicture);
    END; {CommandInfo}


    PROCEDURE UpdatePicture(whichWindow: WindowPtr);
    { This draws our picture into the XWindow }
    VAR
      myPictureHndl: LongInt;
      destRect:     Rect;
    BEGIN

      { Retrieve the handle to our picture }
      myPictureHndl := GetXWindowValue(whichWindow);

      { Display message if unable to load the picture }
      IF myPictureHndl = 0 THEN BEGIN
        WITH whichWindow^.portRect DO SetRect(destRect, 0, 0, right,
                                bottom);
        EraseRect(destRect);
        MoveTo(10,13);
        DrawString(CantDrawStr);
         EXIT(UpdatePicture);
        END; {if}

      { Draw picture in upper left corner }
      WITH PicHndl(myPictureHndl)^^.picFrame DO
        SetRect(destRect, 0, 0, right-left, bottom-top);
      DrawPicture(PicHndl(myPictureHndl), destRect);
    END; {UpdatePicture}


    PROCEDURE CleanUpMemory(whichWindow: WindowPtr);
    { Remove our picture from memory when we close }
    VAR
      myPictureHndl:  LongInt;
    BEGIN
      myPictureHndl := GetXWindowValue(whichWindow);
      IF myPictureHndl = 0 THEN EXIT(CleanUpMemory);
      KillPicture(PicHndl(myPictureHndl));
      SetXWindowValue(whichWindow, 0);   { Just to be safe - clear
                                this value }
    END; {CleanUpMemory}


    PROCEDURE HandleWindowClick(whichWindow: WindowPtr; ourEvent:
                        EventRecord);
    { The user has clicked in our window, handle tracking the click }

      FUNCTION MouseUpInWindow: BOOLEAN;
      { Handle tracking a mouseClick in our window }
      VAR
        mouseLoc:     Point;
        oldInWind:    BOOLEAN;
        inWind:    BOOLEAN;
        targetRect:    Rect;
      BEGIN
        oldInWind := FALSE;
        inWind := TRUE;
        WITH whichWindow^.portRect DO SetRect(targetRect, 0, 0, right,
                                bottom);
        REPEAT
          IF oldInWind <> inWind THEN BEGIN
        InvertRect(targetRect);
        oldInWind := inWind;
          END; {if}
          GetMouse(mouseLoc);
          inWind := PtInRect(mouseLoc, targetRect);
        UNTIL NOT Button(0);
        IF oldInWind THEN InvertRect(targetRect);    {Turn off hilite}
        MouseUpInWindow := inWind;  { Return whether mouseUp occurred
                            in the rect }
      END; {MouseUpInWindow}

    BEGIN
      IF MouseUpInWindow THEN SendHCMessage('play "Harpsichord" tempo
                                400 "c d e"');
    END; {HandleWindowClick}


    PROCEDURE HandleEvents;
    { Handle events specific to our XWindow }
    VAR
      myEventInfo:    XWEventInfoPtr;
      window:    WindowPtr;
      event:        EventRecord;
    BEGIN
        myEventInfo := XWEventInfoPtr(paramPtr^.params[1]);
        window := myEventInfo^.eventWindow;
        event := myEventInfo^.event;

       CASE event.what OF
         xOpenEvt:        XWAllowReEntrancy(window, TRUE, TRUE);
         updateEvt:        UpdatePicture(window);
         mouseDownEvt:    HandleWindowClick(window, event);
           xCloseEvt:        CleanUpMemory(window);
         xCursorWithin:    paramPtr^.passFlag := TRUE;  { Let HC
                                change our cursor }
       END; {case}
    END; {HandleEvents}


    PROCEDURE SetUpContents(resName: Str255);
    { Create the contents of our window }
    VAR
      myPictureHndl:  PicHndl;
      homeFile:      INTEGER;
      pictureID:      LongInt;
    BEGIN
      IF NOT FindNamedResource(rPicture, resName, homeFile, pictureID)
THEN
        EXIT(SetUpContents);
      Handle(myPictureHndl) := LoadResource(rPicture, pictureID);
      IF _toolErr <> 0 THEN EXIT(SetUpContents);
      DetachResource(rPicture, pictureID);
      IF _toolErr <> 0 THEN BEGIN
        ReleaseResource(3, rPicture, pictureID);
        EXIT(SetUpContents);
       END; {if}
      { Have HyperCard save handle to our picture resource }
      SetXWindowValue(sampleXWindow, LongInt(myPictureHndl));
    END; {HandleEvents}


    FUNCTION CorrectVersion: BOOLEAN;
    { This returns true if the version of HyperCard is >= minVersion }
    CONST
      minVersion = '1.1';
    VAR
      tempHandle:    Handle;
      tempStr:    Str255;
    BEGIN
      tempHandle := EvalExpr('the version');
      ZeroToPas(tempHandle^, tempStr);
      IF temphandle <> NIL THEN DisposeHandle(tempHandle);
      CorrectVersion := tempStr >= minVersion;
    END; {CorrectVersion}


  BEGIN
    pCount := paramPtr^.paramCount;

    { If the paramCount is negative, we have been called in response
        to an event }
    IF pCount < 0 THEN BEGIN
      HandleEvents;
      EXIT(XPicture);
    END; {if}


    { Display help or copyright info in response to "?" or "!" }
    IF pCount >= 1 THEN BEGIN
      ZeroToPas(paramPtr^.params[1]^, str);
      IF str = '!' THEN CommandInfo(CopyrightStr);
      IF str = '?' THEN CommandInfo(HelpStr);
    END; {if}

    { We''ll take one or two parameters }
    IF (pCount < 1) OR (pCount > 2) THEN HTError;

    {Make sure we are running at least version 1.1 of HyperCard IIGS}
    IF NOT CorrectVersion THEN ReturnResult(WrongVersionStr);

    IF pCount = 1 THEN windowStyle := xWindoidStyle
    ELSE BEGIN
      ZeroToPas(paramPtr^.params[2]^, styleStr);
      IF StringEqual(styleStr, RectStr1) THEN windowStyle :=
                                        xRectStyle
      ELSE IF StringEqual(styleStr, RectStr2) THEN windowStyle :=
                                        xRectStyle
      ELSE IF StringEqual(styleStr, ShadowStr) THEN windowStyle :=
                                        xShadowStyle
      ELSE IF StringEqual(styleStr, DialogStr) THEN windowStyle :=
                                        xDialogStyle
      ELSE windowStyle := xWindoidStyle;
    END; {else}

    SetRect(windRect, 50, 76, 250, 140);
    sampleXWindow := NewXWindow(windRect, str, FALSE, windowStyle);
    IF sampleXWindow = NIL THEN ReturnResult(CreateErrStr);

    SetUpContents(str);    { Create the contents for the window }

    ShowWindow(sampleXWindow);
  END;

END.    { of the dummy unit    }